<!DOCTYPE html>
<html lang="en" >
<head>
    <title>Atomsk - FAQ - Pierre Hirel</title>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <link rel="stylesheet" media="screen" type="text/css" title="Default" href="./default.css" />
    <link rel="icon" href="../img/atomsk_logo.png" type="image/png" />
    <script language="javascript" type="text/javascript">
    function showHide(shID) {
      if (document.getElementById(shID)) {
          if (document.getElementById(shID+'-show').style.display != 'block') {
            document.getElementById(shID+'-show').style.display = 'block';
          }
          else {
            document.getElementById(shID+'-show').style.display = 'none';
          }
      }
    }
    </script>
</head>
   
<body>

<p><a href="./index.html">Back to main menu</a></p>

<h2>FAQ - Frequently Asked Questions</h2>

<h3>General</h3>

<ul>

<li><a href="#" id="genwhat" class="showLink" onclick="showHide('genwhat');return false;"><strong>What is Atomsk?</strong></a></li>

<div id="genwhat-show" class="more"><p>Atomsk is a command-line program designed for people who perform numerical simulations in the areas of materials physics or chemistry, as well as people who wish to make illustrations in those areas. Atomsk allows to build and manipulate atomic systems, and generate data files for a variety of programs to perform <em>ab initio</em> calculations, classical molecular dynamics simulations, TEM image simulations, or visualization.</p></div>

<li><a href="#" id="genname" class="showLink" onclick="showHide('genname');return false;"><strong>Why is that program named Atomsk ? How should I spell it?</strong></a></li>

<div id="genname-show" class="more"><p>Atomsk stands for <strong>Atom</strong>, <strong>M</strong>olecule, <strong>M</strong>aterial <strong>S</strong>oftware <strong>K</strong>it. It is quite short which is convenient when you type it several times a day in your command-line, and the presence of the sound "atom" suggests that this code deals with atomic systems.</p>

<p>The program name should be spelled with an uppercase first letter, followed by lowercase letters, as follows: <strong>Atomsk</strong>. Other variants, like "atomsk" or "ATOMSK", should be avoided.</p></div>


<li><a href="#" id="genpurp" class="showLink" onclick="showHide('genpurp');return false;"><strong>Why create such a program?</strong></a></li>

<div id="genpurp-show" class="more"><p>After some time writing various small programs to design atomic systems, one quickly realizes that the same basic operations must be re-coded over and over again: building supercells, wrapping atoms into the box, deform the box, and so on. Therefore you end up copy/pasting the same routines (or worse, re-write them from scratch) for every different system (fcc, bcc, diamond lattices...). In addition, if you want to use another simulation or visualization software, you may have to re-write your codes to comply with the file formats of the target software.</p>

<p>I thought it would be more efficient to write a general-purpose program that could perform these operations in any system, no matter the atom species or the lattice, and no matter what the input and output formats are. Such is the purpose of Atomsk.</p></div>


<li><a href="#" id="genprinc" class="showLink" onclick="showHide('genprinc');return false;"><strong>What are the principles behind Atomsk?</strong></a></li>

<div id="genprinc-show" class="more"><p>Atomsk follows two principles. The first one states that when you want to do something simple, then it should be simple to do it. An example of something "simple" is to convert a file: we don't want to spend hours reading documentation just to figure out how to convert one file. That is why in Atomsk you have to enter only the two informations: the name of the file you want to convert, and the final file format, e.g.:</p>

<p><code class="command">atomsk file.xsf cfg</code></p>

<p>A corollary of this principle is that when you want to do something complicated (build complex systems, compute some property...), then it may not be so simple to do it. Some programs allow to perform very complex tasks simply, but they are very specialized software -while Atomsk tries to be quite general and applicable to many systems.</p>

<p>The second principle is that when one reads a command-line of Atomsk, what it does should be obvious and non-ambiguous. For example the following command:</p>

<p><code class="command">atomsk --create fcc 4.02 Al -duplicate 10 10 4 supercell.xsf</code></p>

<p>will obviously create a 10x10x4 supercell of fcc aluminum, and write it to the file <code>supercell.xsf</code>. This principle ensures that if you write such commands in scripts (e.g. bash scripts) and read them again months or years later, you will still be able to understand quickly what you did.</p>
</div>


<li><a href="#" id="gendl" class="showLink" onclick="showHide('gendl');return false;"><strong>Where can I download Atomsk?</strong></a></li>

<div id="gendl-show" class="more"><p>It is recommended to visit the official Web site: <a href="http://atomsk.univ-lille.fr/">http://atomsk.univ-lille.fr/</a></p>

<p>Download the executable binary for your platform. You can also download the source code if you wish to compile the code yourself or have a look at it.</p></div>


<li><a href="#" id="gencite" class="showLink" onclick="showHide('gencite');return false;"><strong>How should I cite Atomsk?</strong></a></li>

<div id="gencite-show" class="more"><p>If you use Atomsk in your work, the citation of the following article will be greatly appreciated:</p>
<ul>
  <li>Pierre Hirel, <em>Comput. Phys. Comm.</em> <strong>197</strong> (2015) 212</li>
</ul>
</div>

</ul>


<h3>Usage</h3>

<ul>


<li><a href="#" id="usetype" class="showLink" onclick="showHide('usetype');return false;"><strong>What type of systems can I construct with Atomsk?</strong></a></li>

<div id="usetype-show" class="more"><p>Atomsk was primarily designed to construct and manipulate atomic systems for materials physics. It has facilities to construct supercells, insert defects (vacancies, interstitials, dislocations, cracks...), and to read and write file formats commonly used in that field.</p>

<p>Although Atomsk can read and write some file formats commonly used in chemistry or biology (DL_POLY, PDB, XYZ...), you may find it not so suitable for constructing molecular systems. Atomsk does not understand molecules, bonds, and lacks the common tools used to construct such systems (e.g. solvating).</p></div>


<li><a href="#" id="useprec" class="showLink" onclick="showHide('useprec');return false;"><strong>What is the precision on atomic positions?</strong></a></li>

<div id="useprec-show" class="more"><p>Internally all real numbers are stored with 64-bits precision. When writing output files, supercell parameters and atom coordinates are written with 8 decimal digits. This is assumed to be sufficient for most applications.</p></div>


<li><a href="#" id="usenp" class="showLink" onclick="showHide('usenp');return false;"><strong>What is the maximum number of atoms that Atomsk can handle?</strong></a></li>

<div id="usenp-show" class="more"><p>In principle the limit is that of 32-bits (4-bytes) integers, i.e. about 2 billions (2<sup>31</sup>). In practice there are good chances that the amount of virtual memory available on the machine will be the limiting factor. Each atom is characterized by its position x, y, z, and its atomic number, which makes a total of four numbers that are saved as 64-bits real numbers: as a result each atom requires 256 bits or 32 bytes of memory. Storing all atoms requires an array of size Nx4, where N is the number of atoms. So, a system of one million atoms will use about 32 MB (or 30.5 MiB), 10 millions atoms will use 320 MB, and so on. So, in order to reach the limit of 2 billions of atoms you will need about 64 GB of memory.</p>

<p>In addition if your system includes shells (in the sense of an ionic core-shell model), it will require a second array of size Nx4. Finally if atoms have auxiliary properties (like forces, velocity...), these properties are also saved in a 64-bits real array of size NxM where M is the number of properties associated with each atom.</p></div>


<li><a href="#" id="useunits" class="showLink" onclick="showHide('useunits');return false;"><strong>What units are used?</strong></a></li>

<div id="useunits-show" class="more"><p>By default angstr&ouml;ms are assumed, although Atomsk just passes the numbers from one file format to another without caring about the units.</p>

<p>Note that Atomsk makes absolutely no implicit transformation of the units. For instance, if you read a file containing atom positions in Bohrs, then in the output file they will also appear in Bohrs. In order to explicitely convert the units of the atom coordinates and cell parameters you can use the <a href="./option_unit.html">option <code>-unit</code></a>.</p></div>


<li><a href="#" id="useprompt" class="showLink" onclick="showHide('useprompt');return false;"><strong>I am faced with a prompt (<code>atomsk&#62;</code>) and I don't know what to do.</strong></a></li>

<div id="useprompt-show" class="more"><p>That means that you have run Atomsk without any argument, either by entering "atomsk" in your command-line, or double-clicking the executable or a link to it. This triggers the <a href="./mode_interactive.html">interactive mode</a>. In this mode the program waits for your commands, and executes them in real-time (if they are valid). In this mode, type "help" to see a list of available commands.</p>

<p>If you do not wish to use Atomsk interactively, then you must run it in a command-line with trailing arguments, for instance:</p>

<p><code class="command">atomsk initial.xsf -duplicate 2 2 2 final.cfg</code></p>
</div>


<li><a href="#" id="usepwd" class="showLink" onclick="showHide('usepwd');return false;"><strong>Where are the output files generated by Atomsk?</strong></a></li>

<div id="usepwd-show" class="more"><p>Atomsk writes files in the current working directory, i.e. the directory where you are when you run Atomsk. Type "pwd" to know the path to that directory, and "ls" to display the list of files in the directory.</p>
</div>


<li><a href="#" id="uselang" class="showLink" onclick="showHide('uselang');return false;"><strong>How do I change the language?</strong></a></li>

<div id="uselang-show" class="more"><p>Atomsk tries to speak your language if it can; otherwise it defaults to English. If you wish to use a specific language, you can use the command-line option "-lang", followed by the two-letter code of your language. Please have a look at the <a href="./progbe_lang.html">list of supported languages</a>.</p>

<p>To make the change more permanent, you can create your own configuration file. Please refer to <a href="./progbe_configfile.html">this page</a> to learn how to set up your own configuration file.</p>
</div>


<li><a href="#" id="usenclo" class="showLink" onclick="showHide('usenclo');return false;"><strong>How many options can I call in a single command-line?</strong></a></li>

<div id="usenclo-show" class="more"><p>There is virtually no limitation, apart from those of your shell itself. Try "<code>getconf ARG_MAX</code>" to know the maximum command line length that your shell supports.</p></div>


<li><a href="#" id="useuc" class="showLink" onclick="showHide('useuc');return false;"><strong>How can I create a unit cell?</strong></a></li>

<div id="useuc-show" class="more"><p>Atomsk can create unit cells of some simple geometries thanks to the <a href="./mode_create.html">mode create</a>. For instance, to create a unit cell of face-centered cubic aluminium (lattice parameter 4.02 &Aring;) and write it to the file <code>aluminum.xsf</code>:</p>

<p><code class="command">atomsk --create fcc 4.02 Al aluminum.xsf</code></p>

<p>However this method is pretty limited, as a lot of lattice types can simply not be generated at all. If you know the space group and Wyckoff positions of the crystal you want to build, then the <a href="http://www.cryst.ehu.es/cryst/get_wp.html">Bilbao Crystallographic server</a> can be extremely helpful to build the crystal. Some other codes can also generate crystal structures given the space group and the Wyckoff positions, like <a href="http://jp-minerals.org/vesta/">VESTA</a>, <a href="https://wiki.fysik.dtu.dk/ase/">ASE</a>, or some simulation codes like <a href="http://xmd.sourceforge.net/">XMD</a> or <a href="https://nanochemistry.curtin.edu.au/gulp/">GULP</a>.</p>

<p>It is possible that Atomsk will include such methods in future releases, however this is not planned at the moment.</p></div>


<li><a href="#" id="usesc" class="showLink" onclick="showHide('usesc');return false;"><strong>I have a unit cell, how do I generate a supercell?</strong></a></li>

<div id="usesc-show" class="more"><p>This can be done with the <a href="./option_duplicate.html">option <code>-duplicate</code></a>. If your unit cell is in the file <code>unitcell.xsf</code>, and you want to create a 4x4x2 supercell, the command would be:</p>

<p><code class="command">atomsk unitcell.xsf -duplicate 4 4 2 supercell.xsf</code></p>

<p>and the supercell will be written in the file <code>supercell.xsf</code>.</p>
</div>


<li><a href="#" id="useconv" class="showLink" onclick="showHide('useconv');return false;"><strong>How can I convert a file for a specific simulation or visualization software?</strong></a></li>

<div id="useconv-show" class="more"><p>Call Atomsk with the name of the input file and the target file format (check <a href="./formats.html">this page</a> for a list of supported file formats). For instance, to convert the file "file.xsf" into the CFG format for Atomeye enter:</p>

<p><code class="command">atomsk file.xsf cfg</code></p>

<p>Several file formats can be specified, e.g. the following will generate files in both CFG format (Atomeye) and LAMMPS data file format:</p>

<p><code class="command">atomsk file.xsf cfg lmp</code></p>
</div>


<li><a href="#" id="usecalc" class="showLink" onclick="showHide('usecalc');return false;"><strong>I created an input file with Atomsk, but then my <em>ab initio</em> or molecular dynamics code does not run.</strong></a></li>

<div id="usecalc-show" class="more"><p>While it is true that one of the purposes of Atomsk is to help to prepare files for simulations, it is not meant to prepare all the files nor set all the parameters for your simulation. Most of the time, Atomsk will only prepare a draft that you will have to edit before running a simulation. Editing such an input file means that you must know what you want to do and how to do it with the simulation code(s) that you are using. If it is not the case, then don't expect Atomsk to help you: refer to the documentation of the code you are using.</p></div>


<li><a href="#" id="usescript" class="showLink" onclick="showHide('usescript');return false;"><strong>Is it possible to write scripts for Atomsk?</strong></a></li>

<div id="usescript-show" class="more"><p>Yes, there are actually 3 ways to work with "script files" with Atomsk.</p>

<p>The first and natural way is to use bash scripts (or batch in Windows). Any variable defined in the bash script can be used in the command-line with atomsk, since these variables are automatically interpreted by the shell before running the command. All the examples provided with the code in the "examples" folder use this capability.</p>

<p>Second, it is also possible to write some options in a file, for instance:</p>

<div class="txtfile">
<h5>my_options.txt</h5>
<p><code># options for atomsk<br/>
duplicate 40 30 1<br/>
deform x 3% 0.33<br/>
</code></p></div>

<p>and then run the program with the <a href="./option_options.html">option <code>-options</code></a>, e.g.:</p>

<p><code class="command">atomsk unitcell.xsf -options my_options.txt final.xsf</code></p>

<p>And, last but not least, it is also possible to write "atomsk scripts" and feed the program with it. This capability is detailed in the <a href="./mode_interactive.html">mode interactive</a>.</p>
</div>


<li><a href="#" id="useverb" class="showLink" onclick="showHide('useverb');return false;"><strong>I do not like the way Atomsk always prints information on my screen, how do I change that?</strong></a></li>

<div id="useverb-show" class="more"><p>The printing of information is the default behaviour of the program, as a way to tell exactly what it is doing. This default behaviour can be changed thanks to the <a href="./progbe_verb.html">command-line parameter <code>-verbosity</code></a>. For instance, to make the program completely silent, call it with <code>-v 0</code>.</p>

<p>To make this change more permanent, it is also possible to create a <a href="progbe_configfile.html">personal configuration file</a>. If you are using a GNU/Linux system, create a file <code>~/.config/atomsk.conf</code> and write into it: <code>verbosity 0</code>.</p>

<p>Note that even when the verbosity is set to zero, warning and error messages will still be displayed on screen. To avoid that, use the standard redirection: <code>&#62;/dev/null 2&#62;&amp;1</code>.</div>


<li><a href="#" id="usecrash" class="showLink" onclick="showHide('usecrash');return false;"><strong>When running Atomsk, it crashed.</strong></a></li>

<div id="usecrash-show" class="more"><p>The code is supposed to detect possible causes of errors and exit smoothly, but in some cases it is possible that it terminates abruptly due to a segmentation fault or any other form of error or crash. The latter behaviour is most likely caused by a bug in the program, and that can be anything. The best line of action is to report such a bug by sending an email to <a href="./contact.html">the author</a>, with your input file and the complete command-line parameters that you used to run Atomsk. Hopefully the bug will be fixed in a future release.</p>

<p>Please note that if you only curse at the program (or the author) but do not report the bug, it is very unlikely to get fixed.</p></div>

</ul>



<h3 id="compil">Compilation / Installation</h3>

<ul>

<li><a href="#" id="instcomp" class="showLink" onclick="showHide('instcomp');return false;"><strong>The program won't compile with my compiler.</strong></a></li>

<div id="instcomp-show" class="more"><p>A lot of efforts were made to test the program with many different compilers (GNU Fortran, g95, Intel Fortran) on many platforms (different flavors of Linux and Windows), please check the <a href="./install.html">installation page</a> for a list of tested compilers. However for obvious reasons of limited available time and resources <em>all</em> possible environments were not tested -therefore it is still possible that, in some particular cases, the compilation will fail.</p>

<p>Some old versions of some compilers are known to cause problems with the present program. For instance Atomsk will <em>not</em> compile with gfortran 4.1, but compiles flawlessly with gfortran 4.4. The best is to use an up-to-date version of your compiler. If it still does not work, try with another compiler.</p></div>


<li><a href="#" id="instundef" class="showLink" onclick="showHide('instundef');return false;"><strong>When compiling I get the error message "<strong>undefined reference to dgesv_</strong>" (or a similar message).</strong></a></li>

<div id="instundef-show" class="more"><p>That means that the compiler cannot link Atomsk to the LAPACK library. First, make sure that LAPACK is installed on your system, and compiled with the same compiler as the one you are using for Atomsk. Then, make sure that the <code>LAPACK</code> variable (in the Makefile you are using) points correctly to the LAPACK library.</a></p></div>



<li><a href="#" id="instwin" class="showLink" onclick="showHide('instwin');return false;"><strong>Does this program work on Windows XP, Vista, Seven, 3.1 or whatsoever?</strong></a></li>

<div id="instwin-show" class="more"><p>Actually yes, Atomsk runs natively on Microsoft&reg; Windows&reg; systems. The most simple thing to do is to download the Windows executable (atomsk.exe) from the <a href="http://atomsk.univ-lille.fr/dl.php">download page</a>, and just run it.</p>

<p>If you are bold enough to try and compile the code under Microsoft&reg; Windows&reg;, follow the <a href="./install.html">installation instructions page</a>. You will have to install the program <a href="http://gnuwin32.sourceforge.net/">GNU Make</a> for the "<code>make</code>" command to work, as well as a Fortran 95 compiler (<a href="http://www.mingw.org/">MinGW</a> is recommended). The LAPACK library is also needed, look at <a href="http://gcc.gnu.org/wiki/LAPACK%20on%20Windows">this page (GNU Fortran)</a> and/or <a href="http://icl.cs.utk.edu/lapack-for-windows/">this page (Intel&reg; Fortran)</a>. A Makefile for Windows is provided in the <em>src</em> directory  (<code>Makefile.windows</code>), you may edit it to suit your system. Then run GNU Make by typing something like:</p>

<p><code class="command">make.exe -f Makefile.windows atomsk</code></p>

<p>Alternatively Atomsk should also work under Windows in a Linux-like environment such as <a href="http://www.cygwin.com">Cygwin</a>, although this was not tested.</p></div>


<li><a href="#" id="instbin" class="showLink" onclick="showHide('instbin');return false;"><strong>Can you provide a package (rpm, deb...) for my favorite GNU/Linux distribution?</strong></a></li>

<div id="instbin-show" class="more"><p>No. Although I admit it would be much desirable to have Atomsk packaged, I have neither the time or the knowledge of packaging processes to do it properly. Volunteers for this task are of course welcome.</p>

<p>As an alternative, binaries for Linux are provided on the <a href="http://atomsk.univ-lille.fr/">atomsk Web page</a>.</p></div>


<li><a href="#" id="instlinux" class="showLink" onclick="showHide('instlinux');return false;"><strong>On Linux, why does the program install in <em>/usr/local/bin</em> by default?</strong></a></li>

<div id="instlinux-show" class="more"><p>The package managers that come with most GNU/Linux distributions maintain their supported executables in the <em>/usr/bin</em> directory. So, first of all, you do not want to screw up this directory -that is why Atomsk does not touch it. The <em>/usr/local/bin</em> directory is actually intended for receiving "custom" binaries (like the present program) that can usually be run by any user.</p>

<p>Another possibility would be to install Atomsk in the <em>/opt/bin</em> directory, which is also reserved for custom packages and binaries. This can be done by modifying the <code>INSTPATH</code> variable in the <code>Makefile</code> before using the "<code>make install</code>" command.</p>

<p>If you are unsure about the best option for your system, just use the default setup or ask your local system administrator.</p></div>

</ul>



<h3>Development</h3>

<ul>


<li><a href="#" id="devcloc" class="showLink" onclick="showHide('devcloc');return false;"><strong>How many lines of code does the program count?</strong></a></li>

<div id="devcloc-show" class="more"><p>As of version Beta 0.11 Atomsk counts about 46,000 lines of code, and about 25,000 lines of comments, contained in about 150 source files.</p></div>


<li><a href="#" id="devgui" class="showLink" onclick="showHide('devgui');return false;"><strong>Will a graphical user interface (GUI) be added?</strong></a></li>

<div id="devgui-show" class="more"><p>Some users feel more comfortable with fancy windows and popping menus, instead of an unfriendly terminal. They will be very disappointed by Atomsk. This code is designed to be used as a command-line tool, which means that it must be lean and fast, run on remote machines, and be called in bash scripts. It is difficult to fulfill these scopes with a GUI. So the short answer is no: it is not intended that Atomsk will ever run through a GUI. If you do not like command-line and are looking for a user-friendly GUI, then Atomsk is probably not what you are looking for.</p></div>


<li><a href="#" id="devadd" class="showLink" onclick="showHide('devadd');return false;"><strong>Can you add the support for the format X / Can you add option X?</strong></a></li>

<div id="devadd-show" class="more"><p>If I need it or if I am in a really good mood I will add the support for new file formats and new transformations. However if you need something peculiar you will probably get it faster if you program it yourself. Check the <a href="./developers.html">information for developers</a>.</p></div>


<li><a href="#" id="devlang" class="showLink" onclick="showHide('devlang');return false;"><strong>Why is that program written in bloody Fortran and not Python/C/C++/Java/&#60;your favorite language here&#62;?!?</strong></a></li>

<div id="devlang-show" class="more"><p>Primarily, because Fortran is the language I know best. And <em>a posteriori</em> I don't regret it: Fortran can natively handle complex numbers very easily, and utilize LAPACK (a library also written in Fortran) very simply. However, since Atomsk is <em>libre</em> software, it is part of your rights to re-code it in your favorite language if you are willing to.</p></div>

</ul>


<p><a href="./index.html">Back to main menu</a></p>

</body>

</html>
